=begin pod

=TITLE class Regex

=SUBTITLE String pattern

    class Regex is Method { }

A regex is a kind of pattern that describes a set of strings. The process of
finding out whether a given string is in the set is called I<matching>. The
result of such a matching is a L<Match> object, which evaluates to C<True> in
boolean context if the string is in the set.

A regex is typically constructed by a regex literal

    rx/ ^ab /;      # describes all strings starting with 'ab'
    / ^ ab /;       # same
    rx/ \d ** 2/;   # describes all strings containing at least two digits

X<|prefix &>
A named regex can be defined with the C<regex> declarator followed by its
definition in curly braces. Since any regex does C<Callable> introspection requires
referencing via C<&>-sigil.

    my regex R { \N };
    say &R.^name; # OUTPUT: «Regex␤»

To match a string against a regex, you can use the smart match operator:

    my $match = 'abc' ~~ rx/ ^ab /;
    say $match.Bool;                # OUTPUT: «True␤»
    say $match.orig;                # OUTPUT: «abc␤»
    say $match.Str;                 # OUTPUT: «ab␤»
    say $match.from;                # OUTPUT: «0␤»
    say $match.to;                  # OUTPUT: «2␤»

Or you can evaluate the regex in boolean context, in which case it matches
against the C<$_> variable

    $_ = 'abc';
    if / ^ab / {
        say '"abc" begins with "ab"';
    }
    else {
        say 'This is a weird alternative Universe';
    }

=head1 Methods

=head2 method ACCEPTS

    multi method ACCEPTS(Regex:D: Mu --> Match:D)
    multi method ACCEPTS(Regex:D: @)
    multi method ACCEPTS(Regex:D: %)

Matches the regex against the argument passed in.
If the argument is L<Positional>, it returns the first successful match of any
list item. If the argument is L<Associative>, it returns the first successful
match of any key. Otherwise it interprets the argument as a L<Str> and matches
against it.

In the case of Positional and Associative matches, L<Nil> is returned on
failure.

=head2 method Bool

    multi method Bool(Regex:D: --> Bool:D)

Matches against the caller's L<$_|/syntax/$_> variable, and returns C<True> for a match or
C<False> for no match.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
